"""
MicroPython network module type stubs.

This file provides type hints for the network module.
"""

from typing import Optional, Tuple, List

# Network interface types
STA_IF: int = 0  # Station interface (client mode)
AP_IF: int = 1   # Access Point interface (AP mode)

# Authentication modes
AUTH_OPEN: int = 0
AUTH_WEP: int = 1
AUTH_WPA_PSK: int = 2
AUTH_WPA2_PSK: int = 3
AUTH_WPA_WPA2_PSK: int = 4

# Connection status
STAT_IDLE: int = 0
STAT_CONNECTING: int = 1
STAT_WRONG_PASSWORD: int = 2
STAT_NO_AP_FOUND: int = 3
STAT_CONNECT_FAIL: int = 4
STAT_GOT_IP: int = 5


class WLAN:
    """WiFi network interface."""

    def __init__(self, interface_id: int) -> None:
        """
        Initialize WLAN interface.

        Args:
            interface_id: STA_IF (client) or AP_IF (access point)

        Example:
            >>> import network
            >>> wlan = network.WLAN(network.STA_IF)
        """
        ...

    def active(self, is_active: Optional[bool] = None) -> bool:
        """
        Get or set interface active state.

        Args:
            is_active: True to activate, False to deactivate

        Returns:
            Current active state

        Example:
            >>> wlan.active(True)
            >>> print(wlan.active())
            True
        """
        ...

    def connect(
        self,
        ssid: Optional[str] = None,
        password: Optional[str] = None,
        *,
        bssid: Optional[bytes] = None
    ) -> None:
        """
        Connect to WiFi network.

        Args:
            ssid: Network name (SSID)
            password: Network password
            bssid: BSSID of specific AP (optional)

        Example:
            >>> wlan.connect('MyWiFi', 'password123')
            >>> while not wlan.isconnected():
            ...     pass
        """
        ...

    def disconnect(self) -> None:
        """Disconnect from WiFi network."""
        ...

    def isconnected(self) -> bool:
        """
        Check if connected to network.

        Returns:
            True if connected, False otherwise
        """
        ...

    def scan(self) -> List[Tuple[bytes, bytes, int, int, int, int]]:
        """
        Scan for available WiFi networks.

        Returns:
            List of tuples: (ssid, bssid, channel, RSSI, authmode, hidden)

        Example:
            >>> networks = wlan.scan()
            >>> for ssid, bssid, channel, rssi, authmode, hidden in networks:
            ...     print(ssid.decode())
        """
        ...

    def status(self, param: Optional[str] = None) -> int:
        """
        Get connection status.

        Args:
            param: Optional parameter name

        Returns:
            Status code or parameter value
        """
        ...

    def ifconfig(
        self,
        config: Optional[Tuple[str, str, str, str]] = None
    ) -> Tuple[str, str, str, str]:
        """
        Get or set network interface configuration.

        Args:
            config: Tuple of (ip, subnet, gateway, dns)

        Returns:
            Current configuration as (ip, subnet, gateway, dns)

        Example:
            >>> print(wlan.ifconfig())
            ('192.168.1.100', '255.255.255.0', '192.168.1.1', '8.8.8.8')
            >>> wlan.ifconfig(('192.168.1.100', '255.255.255.0', '192.168.1.1', '8.8.8.8'))
        """
        ...

    def config(self, param: Optional[str] = None, **kwargs) -> any:
        """
        Get or set interface configuration parameters.

        Common parameters:
            - mac: MAC address (bytes)
            - essid: Network SSID (str) - AP mode
            - channel: WiFi channel (int) - AP mode
            - hidden: Hide SSID (bool) - AP mode
            - authmode: Authentication mode (int) - AP mode
            - password: WiFi password (str) - AP mode
            - dhcp_hostname: DHCP hostname (str) - STA mode
            - reconnects: Auto-reconnect attempts (int) - STA mode

        Example:
            >>> mac = wlan.config('mac')
            >>> wlan.config(dhcp_hostname='mydevice')
            >>> wlan.config(essid='MyAP', password='12345678')  # AP mode
        """
        ...


class LAN:
    """Ethernet LAN interface (platform dependent)."""

    def __init__(
        self,
        id: int = 0,
        *,
        phy_type: Optional[int] = None,
        phy_addr: Optional[int] = None,
        ref_clk_mode: Optional[int] = None
    ) -> None:
        """Initialize Ethernet interface."""
        ...

    def active(self, is_active: Optional[bool] = None) -> bool:
        """Get or set interface active state."""
        ...

    def isconnected(self) -> bool:
        """Check if Ethernet cable is connected."""
        ...

    def ifconfig(
        self,
        config: Optional[Tuple[str, str, str, str]] = None
    ) -> Tuple[str, str, str, str]:
        """Get or set network configuration."""
        ...

    def config(self, param: Optional[str] = None, **kwargs) -> any:
        """Get or set interface parameters."""
        ...


class PPP:
    """PPP network interface (platform dependent)."""

    def __init__(self, uart: any) -> None:
        """Initialize PPP interface on UART."""
        ...

    def active(self, is_active: Optional[bool] = None) -> bool:
        """Get or set interface active state."""
        ...

    def isconnected(self) -> bool:
        """Check if PPP connection is established."""
        ...

    def connect(
        self,
        username: Optional[str] = None,
        password: Optional[str] = None
    ) -> None:
        """Establish PPP connection."""
        ...

    def disconnect(self) -> None:
        """Disconnect PPP connection."""
        ...

    def ifconfig(self) -> Tuple[str, str, str, str]:
        """Get network configuration."""
        ...


def hostname(name: Optional[str] = None) -> str:
    """
    Get or set network hostname.

    Args:
        name: New hostname

    Returns:
        Current hostname
    """
    ...


def phy_mode(mode: Optional[int] = None) -> int:
    """
    Get or set PHY mode (ESP8266 only).

    Args:
        mode: PHY mode constant

    Returns:
        Current PHY mode
    """
    ...
